Skip to content
lab components / Actions and controls

Toggle Switch

Toggle Switch allows users to turn things on or off with an immediate effect.

ExamplesPropertiesGuidelines

This is a Lab component!

That means it doesn't satisfy our definition of done and may be changed or even deleted. For an exact status, please reach out to the Fancy team through the dev_fancy or ux_fancy channels.

import { ToggleSwitch } from "@siteimprove/fancylab";

#Examples

Think of ToggleSwitch as a physical switch that allows the user to turn things on or off, like a light switch. Use ToggleSwitch when the user has the freedom and control to change their settings as needed.

A ToggleSwitch should always have a label and a default value, either true (on) or false (off).

const [checked, setChecked] = React.useState(false); return <ToggleSwitch label="Label" value={checked} onChange={setChecked} />;

#Label Position

Depending on layout constraints, labels can be positioned to the left or right of a ToggleSwitch. It is best to place the labels to the left of the ToggleSwitch so that users can more easily read the text and understand the meaning in the language written from left to right.


const [checked, setChecked] = React.useState(false); return ( <> <ToggleSwitch label="Label in the left" labelPosition="left" value={checked} onChange={setChecked} /> <br /> <ToggleSwitch label="Label in the right" labelPosition="right" value={checked} onChange={setChecked} /> </> );

#Custom Label

Use a custom label to explain what happens when a ToggleSwitch is on or off. Explain how turning a switch on or off affects a user's decision.

const [checked, setChecked] = React.useState(false); return ( <ToggleSwitch label={ <InlineText emphasis={checked ? "medium" : "normal"}> <Tooltip variant={{ type: "text" }} content="This is a tooltip"> Label with tooltip </Tooltip> </InlineText> } value={checked} onChange={setChecked} /> );

#Properties

PropertyDescriptionDefinedValue
onChangeRequired
functionCallback to switch the value
valueRequired
booleanDetermines the state of the toggle switch
labelOptional
elementText to be displayed next to the toggle switch
aria-labelOptional
stringText to describe the function of toggle switch
aria-describedbyOptional
stringID of an an element that describes what the toggle switch is for
disabledOptional
booleanDisabled state
labelPositionOptional
"left" | "right"Should the label be displayed on the right or the left side of the toggle switch - default is right
fullWidthOptional
booleanShould the toggle element be full width?
data-observe-keyOptional
stringUnique string, used by external script e.g. for event tracking
classNameOptional
stringCustom className that's applied to the outermost element (only intended for special cases)
styleOptional
objectStyle object to apply custom inline styles (only intended for special cases)
tabIndexOptional
numberTab index of the outermost HTML element of the component
onKeyDownOptional
functionCallback for onKeyDown event
onMouseDownOptional
functionCallback for onMouseDown event
onMouseEnterOptional
functionCallback for onMouseEnter event
onMouseLeaveOptional
functionCallback for onMouseLeave event
onFocusOptional
functionCallback for onFocus event
onBlurOptional
functionCallback for onBlur event

#Guidelines

#Best practices

#General

Use ToggleSwitch when

  • applying a system state, or view not a contextual one.
  • providing binary options, such as on/off or true/false.
  • activating or deactivating something immediately.
  • the user receives a clear visual cue between the two toggle states.

#Placement

ToggleSwitch is typically used in the following place:

  • System settings

    ToggleSwitch can be used to apply system settings or preferences. If you have multiple ToggleSwitch, each item in a set should be controlled independently.

#Do not use when

  • the user controls a single feature or minor setting. In this case, use a standalone Checkbox instead.
  • the user can change at least two options that determine how or what content is displayed on the current page. In this case, use Toggle Group.
  • designing a form. If the user is only allowed to select one option from a list of related items, then you should use Radios.
  • the user must click a button for other changes to take effect.

#Accessibility

This component comes with built-in accessibility, no extra work required.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

  • The text of a label should not be changed depending on its state. Keep the label consistent.
  • Label the ToggleSwitch with one or two words, preferably nouns, that describe what the control does when the switch is on.
  • The label of the ToggleSwitch should be short and direct, e.g. "Email notifications". If in doubt, read the label aloud and add "on/off" at the end. If it does not make sense, rewrite the label.
  • Avoid redundant words that describe the switch itself. For example: "Allow", "Turn on" "Active" and "Enable".
  • Avoid confusing double negatives. For example: "Hide fixed issues".
  • Use sentence case for a label.
  • The toggle label should not be written with questions. For example: “Do you want to receive notifications?”